Markdown Readme.text

   1 Markdown
   2 ========
   3
   4 Version 1.0.3 - Sun 06 Sep 2015
   5
   6 John Gruber
   7 Kyle J. McKay
   8
   9
  10 Introduction
  11 ------------
  12
  13 Markdown is a text-to-HTML conversion tool for web writers. Markdown
  14 allows you to write using an easy-to-read, easy-to-write plain text
  15 format, then convert it to structurally valid XHTML (or HTML).
  16
  17 Thus, "Markdown" is two things: a plain text markup syntax, and a
  18 software tool, written in Perl, that converts the plain text markup
  19 to HTML.
  20
  21 Markdown works both as a Movable Type plug-in and as a standalone Perl
  22 script -- which means it can also be used as a text filter in BBEdit
  23 (or any other application that supporst filters written in Perl).
  24
  25 Full documentation of Markdown's syntax and configuration options is
  26 available in the basics.text and syntax.text files.
  27 (Note: this readme file and the basics and syntax files are formatted
  28 in Markdown.)
  29
  30
  31
  32 Installation and Requirements
  33 -----------------------------
  34
  35 Markdown requires Perl 5.6.0 or later. Welcome to the 21st Century.
  36 Markdown also requires the standard Perl library module `Digest::MD5`.
  37
  38
  39 ### Movable Type ###
  40
  41 Markdown works with Movable Type version 2.6 or later (including
  42 MT 3.0 or later).
  43
  44 1.  Copy the "Markdown.pl" file into your Movable Type "plugins"
  45     directory. The "plugins" directory should be in the same directory
  46     as "mt.cgi"; if the "plugins" directory doesn't already exist, use
  47     your FTP program to create it. Your installation should look like
  48     this:
  49
  50         (mt home)/plugins/Markdown.pl
  51
  52 2.  Once installed, Markdown will appear as an option in Movable Type's
  53     Text Formatting pop-up menu. This is selectable on a per-post basis.
  54     Markdown translates your posts to HTML when you publish; the posts
  55     themselves are stored in your MT database in Markdown format.
  56
  57 3.  If you also install SmartyPants 1.5 (or later), Markdown will offer
  58     a second text formatting option: "Markdown with SmartyPants". This
  59     option is the same as the regular "Markdown" formatter, except that
  60     automatically uses SmartyPants to create typographically correct
  61     curly quotes, em-dashes, and ellipses. See the SmartyPants web page
  62     for more information: <http://daringfireball.net/projects/smartypants/>
  63
  64 4.  To make Markdown (or "Markdown with SmartyPants") your default
  65     text formatting option for new posts, go to Weblog Config ->
  66     Preferences.
  67
  68 Note that by default, Markdown produces XHTML output. To configure
  69 Markdown to produce HTML 4 output, see "Configuration", below.
  70
  71
  72 ### Blosxom ###
  73
  74 Markdown works with Blosxom version 2.x.
  75
  76 1.  Rename the "Markdown.pl" plug-in to "Markdown" (case is
  77     important). Movable Type requires plug-ins to have a ".pl"
  78     extension; Blosxom forbids it.
  79
  80 2.  Copy the "Markdown" plug-in file to your Blosxom plug-ins folder.
  81     If you're not sure where your Blosxom plug-ins folder is, see the
  82     Blosxom documentation for information.
  83
  84 3.  That's it. The entries in your weblog will now automatically be
  85     processed by Markdown.
  86
  87 4.  If you'd like to apply Markdown formatting only to certain posts,
  88     rather than all of them, see Jason Clark's instructions for using
  89     Markdown in conjunction with Blosxom's Meta plugin:
  90
  91     <http://jclark.org/weblog/WebDev/Blosxom/Markdown.html>
  92
  93
  94 ### BBEdit ###
  95
  96 Markdown works with BBEdit 6.1 or later on Mac OS X. (It also works
  97 with BBEdit 5.1 or later and MacPerl 5.6.1 on Mac OS 8.6 or later.)
  98
  99 1.  Copy the "Markdown.pl" file to appropriate filters folder in your
 100     "BBEdit Support" folder. On Mac OS X, this should be:
 101
 102         BBEdit Support/Unix Support/Unix Filters/
 103
 104     See the BBEdit documentation for more details on the location of
 105     these folders.
 106
 107     You can rename "Markdown.pl" to whatever you wish.
 108
 109 2.  That's it. To use Markdown, select some text in a BBEdit document,
 110     then choose Markdown from the Filters sub-menu in the "#!" menu, or
 111     the Filters floating palette
 112
 113
 114
 115 Configuration
 116 -------------
 117
 118 By default, Markdown produces XHTML output for tags with empty elements.
 119 E.g.:
 120
 121     <br />
 122
 123 Markdown can be configured to produce HTML-style tags; e.g.:
 124
 125     <br>
 126
 127
 128 ### Movable Type ###
 129
 130 You need to use a special `MTMarkdownOptions` container tag in each
 131 Movable Type template where you want HTML 4-style output:
 132
 133     <MTMarkdownOptions output='html4'>
 134         ... put your entry content here ...
 135     </MTMarkdownOptions>
 136
 137 The easiest way to use MTMarkdownOptions is probably to put the
 138 opening tag right after your `<body>` tag, and the closing tag right
 139 before `</body>`.
 140
 141 To suppress Markdown processing in a particular template, i.e. to
 142 publish the raw Markdown-formatted text without translation into
 143 (X)HTML, set the `output` attribute to 'raw':
 144
 145     <MTMarkdownOptions output='raw'>
 146         ... put your entry content here ...
 147     </MTMarkdownOptions>
 148
 149
 150 ### Command-Line ###
 151
 152 Use the `--html4tags` command-line switch to produce HTML output from a
 153 Unix-style command line. E.g.:
 154
 155     % perl Markdown.pl --html4tags foo.text
 156
 157 Type `perldoc Markdown.pl`, or read the POD documentation within the
 158 Markdown.pl source code for more information.
 159
 160
 161
 162 Version History
 163 ---------------
 164
 165 1.0.4 (05 Jun 2016):
 166
 167 +       Markdown.pl can now be require'd and the Markdown function called
 168         repeatedly by external code.
 169
 170 +       Backticks (```) delimited code blocks are now handled better and are
 171         no longer subject to any further accidental processing.
 172
 173
 174 1.0.3 (06 Sep 2015):
 175
 176 +       Added support for --htmlroot option to set a URL prefix.
 177
 178 +       Relaxed matching rule for non-indented code blocks.
 179
 180 +       Added support for --imageroot option to set an img URL prefix.
 181
 182
 183 1.0.2 (03 Sep 2015):
 184
 185 +       Added support for -h and --help to display Markdown.pl help.
 186
 187 +       Added support for third-level headers using setext-like
 188         underlining using tildes (`~`'s).
 189
 190 +       Added support for an optional overline using the same character
 191         as the underline when using setext-style headers.
 192
 193 +       Stopped recognizing `_` within words.  The `*` character is still
 194         recognized within words.
 195
 196 +       Added support for strike through text using `~~` similarly to the
 197         way strong works using `**`.
 198
 199 +       Added support for non-indended code blocks by preceding and following
 200         them with a line consisting of 3 backtick quotes (`` ` ``) or more.
 201
 202
 203 1.0.1 (14 Dec 2004):
 204
 205 +       Changed the syntax rules for code blocks and spans. Previously,
 206         backslash escapes for special Markdown characters were processed
 207         everywhere other than within inline HTML tags. Now, the contents
 208         of code blocks and spans are no longer processed for backslash
 209         escapes. This means that code blocks and spans are now treated
 210         literally, with no special rules to worry about regarding
 211         backslashes.
 212
 213         **NOTE**: This changes the syntax from all previous versions of
 214         Markdown. Code blocks and spans involving backslash characters
 215         will now generate different output than before.
 216
 217 +       Tweaked the rules for link definitions so that they must occur
 218         within three spaces of the left margin. Thus if you indent a link
 219         definition by four spaces or a tab, it will now be a code block.
 220
 221                    [a]: /url/  "Indented 3 spaces, this is a link def"
 222
 223                     [b]: /url/  "Indented 4 spaces, this is a code block"
 224
 225         **IMPORTANT**: This may affect existing Markdown content if it
 226         contains link definitions indented by 4 or more spaces.
 227
 228 +       Added `>`, `+`, and `-` to the list of backslash-escapable
 229         characters. These should have been done when these characters
 230         were added as unordered list item markers.
 231
 232 +       Trailing spaces and tabs following HTML comments and `<hr/>` tags
 233         are now ignored.
 234
 235 +       Inline links using `<` and `>` URL delimiters weren't working:
 236
 237                 like [this](<http://example.com/>)
 238
 239 +       Added a bit of tolerance for trailing spaces and tabs after
 240         Markdown hr's.
 241
 242 +       Fixed bug where auto-links were being processed within code spans:
 243
 244                 like this: `<http://example.com/>`
 245
 246 +       Sort-of fixed a bug where lines in the middle of hard-wrapped
 247         paragraphs, which lines look like the start of a list item,
 248         would accidentally trigger the creation of a list. E.g. a
 249         paragraph that looked like this:
 250
 251                 I recommend upgrading to version
 252                 8. Oops, now this line is treated
 253                 as a sub-list.
 254
 255         This is fixed for top-level lists, but it can still happen for
 256         sub-lists. E.g., the following list item will not be parsed
 257         properly:
 258
 259                 +       I recommend upgrading to version
 260                         8. Oops, now this line is treated
 261                         as a sub-list.
 262
 263         Given Markdown's list-creation rules, I'm not sure this can
 264         be fixed.
 265
 266 +       Standalone HTML comments are now handled; previously, they'd get
 267         wrapped in a spurious `<p>` tag.
 268
 269 +       Fix for horizontal rules preceded by 2 or 3 spaces.
 270
 271 +       `<hr>` HTML tags in must occur within three spaces of left
 272         margin. (With 4 spaces or a tab, they should be code blocks, but
 273         weren't before this fix.)
 274
 275 +       Capitalized "With" in "Markdown With SmartyPants" for
 276         consistency with the same string label in SmartyPants.pl.
 277         (This fix is specific to the MT plug-in interface.)
 278
 279 +       Auto-linked email address can now optionally contain
 280         a 'mailto:' protocol. I.e. these are equivalent:
 281
 282                 <mailto:user@example.com>
 283                 <user@example.com>
 284
 285 +       Fixed annoying bug where nested lists would wind up with
 286         spurious (and invalid) `<p>` tags.
 287
 288 +       You can now write empty links:
 289
 290                 [like this]()
 291
 292         and they'll be turned into anchor tags with empty href attributes.
 293         This should have worked before, but didn't.
 294
 295 +       `***this***` and `___this___` are now turned into
 296
 297                 <strong><em>this</em></strong>
 298
 299         Instead of
 300
 301                 <strong><em>this</strong></em>
 302
 303         which isn't valid. (Thanks to Michel Fortin for the fix.)
 304
 305 +       Added a new substitution in `_EncodeCode()`: s/\$/&#036;/g; This
 306         is only for the benefit of Blosxom users, because Blosxom
 307         (sometimes?) interpolates Perl scalars in your article bodies.
 308
 309 +       Fixed problem for links defined with urls that include parens, e.g.:
 310
 311                 [1]: http://sources.wikipedia.org/wiki/Middle_East_Policy_(Chomsky)
 312
 313         "Chomsky" was being erroneously treated as the URL's title.
 314
 315 +       At some point during 1.0's beta cycle, I changed every sub's
 316         argument fetching from this idiom:
 317
 318                 my $text = shift;
 319
 320         to:
 321
 322                 my $text = shift || return '';
 323
 324         The idea was to keep Markdown from doing any work in a sub
 325         if the input was empty. This introduced a bug, though:
 326         if the input to any function was the single-character string
 327         "0", it would also evaluate as false and return immediately.
 328         How silly. Now fixed.
 329
 330
 331
 332 Copyright and License
 333 ---------------------
 334
 335 Copyright (C) 2003-2004 John Gruber
 336 Copyright (C) 2015 Kyle J. McKay
 337 All rights reserved.
 338
 339 Redistribution and use in source and binary forms, with or without
 340 modification, are permitted provided that the following conditions are
 341 met:
 342
 343 * Redistributions of source code must retain the above copyright notice,
 344   this list of conditions and the following disclaimer.
 345
 346 * Redistributions in binary form must reproduce the above copyright
 347   notice, this list of conditions and the following disclaimer in the
 348   documentation and/or other materials provided with the distribution.
 349
 350 * Neither the name "Markdown" nor the names of its contributors may
 351   be used to endorse or promote products derived from this software
 352   without specific prior written permission.
 353
 354 This software is provided by the copyright holders and contributors "as
 355 is" and any express or implied warranties, including, but not limited
 356 to, the implied warranties of merchantability and fitness for a
 357 particular purpose are disclaimed. In no event shall the copyright owner
 358 or contributors be liable for any direct, indirect, incidental, special,
 359 exemplary, or consequential damages (including, but not limited to,
 360 procurement of substitute goods or services; loss of use, data, or
 361 profits; or business interruption) however caused and on any theory of
 362 liability, whether in contract, strict liability, or tort (including
 363 negligence or otherwise) arising in any way out of the use of this
 364 software, even if advised of the possibility of such damage.